web3-provider-engine

What is web3-provider-engine?

The web3-provider-engine is a JavaScript library that allows developers to create custom Ethereum providers. It is designed to be a modular and extensible provider engine that can be used to manage multiple Ethereum networks and handle various types of requests. It is particularly useful for managing custom signing logic, caching, and other middleware functionalities.

What are web3-provider-engine's main functionalities?

Custom Middleware

This feature allows you to add custom middleware to the provider engine. In this example, we add an RPC subprovider to connect to the Ethereum mainnet via Infura. The engine can be extended with additional middleware to handle custom logic.

const Web3ProviderEngine = require('web3-provider-engine');
const RpcSubprovider = require('web3-provider-engine/subproviders/rpc');
const engine = new Web3ProviderEngine();
engine.addProvider(new RpcSubprovider({ rpcUrl: 'https://mainnet.infura.io' }));
engine.start();

Caching

The caching feature allows you to cache certain types of requests to improve performance. By adding a CacheSubprovider, you can cache responses for specific requests, reducing the number of network calls.

const CacheSubprovider = require('web3-provider-engine/subproviders/cache');
engine.addProvider(new CacheSubprovider());

Custom Signing

This feature allows you to implement custom signing logic. The HookedWalletSubprovider can be used to define how accounts are retrieved and how transactions are signed, enabling custom wallet implementations.

const HookedWalletSubprovider = require('web3-provider-engine/subproviders/hooked-wallet');
engine.addProvider(new HookedWalletSubprovider({
  getAccounts: (cb) => cb(null, ['0x1234...']),
  signTransaction: (txParams, cb) => cb(null, '0x5678...')
}));

Other packages similar to web3-provider-engine

ethers

The ethers.js library is a complete and compact library for interacting with the Ethereum blockchain. It provides a more modern and user-friendly API compared to web3-provider-engine, with built-in support for providers, signing, and contract interaction. While web3-provider-engine focuses on middleware and custom provider logic, ethers.js offers a more comprehensive solution for Ethereum development.

web3

The web3.js library is a popular JavaScript library for interacting with the Ethereum blockchain. It provides a wide range of functionalities, including contract interaction, account management, and provider handling. Compared to web3-provider-engine, web3.js offers a more integrated approach with a focus on ease of use and compatibility with the Ethereum ecosystem.

truffle-hdwallet-provider

Truffle HDWallet Provider is a provider engine that allows you to use a mnemonic phrase to generate accounts and sign transactions. It is similar to web3-provider-engine in that it provides custom signing capabilities, but it is specifically designed for use with the Truffle suite of tools and focuses on HD wallet functionality.

README

Web3 ProviderEngine

Web3 ProviderEngine is a tool for composing your own web3 providers.

Originally created for MetaMask, but has been superceded by json-rpc-engine in combination with our eth-json-rpc-middleware. This module is not very actively maintained, so we recommend using that one instead.

Composable

Built to be modular - works via a stack of 'sub-providers' which are like normal web3 providers but only handle a subset of rpc methods.

The subproviders can emit new rpc requests in order to handle their own; e.g. eth_call may trigger eth_getAccountBalance, eth_getCode, and others. The provider engine also handles caching of rpc request results.

const ProviderEngine = require('web3-provider-engine')
const CacheSubprovider = require('web3-provider-engine/subproviders/cache.js')
const FixtureSubprovider = require('web3-provider-engine/subproviders/fixture.js')
const FilterSubprovider = require('web3-provider-engine/subproviders/filters.js')
const VmSubprovider = require('web3-provider-engine/subproviders/vm.js')
const HookedWalletSubprovider = require('web3-provider-engine/subproviders/hooked-wallet.js')
const NonceSubprovider = require('web3-provider-engine/subproviders/nonce-tracker.js')
const RpcSubprovider = require('web3-provider-engine/subproviders/rpc.js')

var engine = new ProviderEngine()
var web3 = new Web3(engine)

// static results
engine.addProvider(new FixtureSubprovider({
  web3_clientVersion: 'ProviderEngine/v0.0.0/javascript',
  net_listening: true,
  eth_hashrate: '0x00',
  eth_mining: false,
  eth_syncing: true,
}))

// cache layer
engine.addProvider(new CacheSubprovider())

// filters
engine.addProvider(new FilterSubprovider())

// pending nonce
engine.addProvider(new NonceSubprovider())

// vm
engine.addProvider(new VmSubprovider())

// id mgmt
engine.addProvider(new HookedWalletSubprovider({
  getAccounts: function(cb){ ... },
  approveTransaction: function(cb){ ... },
  signTransaction: function(cb){ ... },
}))

// data source
engine.addProvider(new RpcSubprovider({
  rpcUrl: 'https://testrpc.metamask.io/',
}))

// log new blocks
engine.on('block', function(block){
  console.log('================================')
  console.log('BLOCK CHANGED:', '#'+block.number.toString('hex'), '0x'+block.hash.toString('hex'))
  console.log('================================')
})

// network connectivity error
engine.on('error', function(err){
  // report connectivity errors
  console.error(err.stack)
})

// start polling for blocks
engine.start()

When importing in webpack:

import * as Web3ProviderEngine  from 'web3-provider-engine';
import * as RpcSource  from 'web3-provider-engine/subproviders/rpc';
import * as HookedWalletSubprovider from 'web3-provider-engine/subproviders/hooked-wallet';

Built For Zero-Clients

The Ethereum JSON RPC was not designed to have one node service many clients. However a smaller, lighter subset of the JSON RPC can be used to provide the blockchain data that an Ethereum 'zero-client' node would need to function. We handle as many types of requests locally as possible, and just let data lookups fallback to some data source ( hosted rpc, blockchain api, etc ). Categorically, we don’t want / can’t have the following types of RPC calls go to the network:

• id mgmt + tx signing (requires private data)
• filters (requires a stateful data api)
• vm (expensive, hard to scale)

Change Log

15.0.0

• uses eth-block-tracker@4, but still provides block body on ('block', 'latest', and 'rawBlock'). Other events ('sync') provide block number hex string instead of block body.
• SubscriptionsSubprovider automatically forwards events to provider
• replacing subprovider implementations with those in eth-json-rpc-engine
• browserify: moved to babelify@10 + @babel/core@7

14.0.0

• default dataProvider for zero is Infura mainnet REST api
• websocket support
• subscriptions support
• remove solc subprovider
• removed dist from git (but published in npm module)
• es5 builds in dist/es5
• zero + ProviderEngine bundles are es5
• web3 subprovider renamed to provider subprovider
• error if provider subprovider is missing a proper provider
• removed need to supply getAccounts hook
• fixed hooked-wallet-ethtx message signing
• fixed hooked-wallet default txParams

13.0.0

• txs included in blocks via eth-block-tracker@2.0.0

12.0.0

• moved block polling to eth-block-tracker.

11.0.0

• zero.js - replaced http subprovider with fetch provider (includes polyfill for node).

10.0.0

• renamed HookedWalletSubprovider personalRecoverSigner to recoverPersonalSignature

9.0.0

• pollingShouldUnref option now defaults to false